<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="Author" content="Build">
   <title>Eclipse Platform Core RFC 0003 - Log File Retrieval</title>
</head>
<body bgcolor="#FFFFFF" >
<div align="right">
  <table border=0 cellspacing=0 cellpadding=2 width="100%">
    <tr> 
		<td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">
			Request For Comment
		</font></font></b></td>
    </tr>
  </table>
</div>
<div align="left"> 
  <h1><img src="../images/idea.gif" width="120" height="86"></h1>
</div>
<h1 align="CENTER">Eclipse Platform Core RFC 0003</h1>
<h1 align="CENTER">Log File Retrieval</h1>
<blockquote> 
  <p><b>Summary</b> <br>
    There is a requirement to make available programatically the information that has 
    been written to the platform log file.
    This RFC describes the proposed approach, which involves adding a new API method
    for obtaining the log file location, and changing the log file format to XML.
  <p><b> By John Arthorne, OTI.</b> <br>
    <font size="-1">Created: 28-NOV-2001.</font> <br>
    <font size="-1">Modified 3-JAN-2002.  Removed API method for log retrieval.</font> <br>
    <font size="-1">Modified 5-DEC-2001.  Sample log file added.</font> <br>
  </blockquote>
<hr>
<h2>The Problem</h2>
<p>
Currently, the only way to programatically access the platform log is by adding a listener by calling
<code>Platform.addLogListener(ILogListener)</code>.  While this approach has many benefits,
there are also some drawbacks:
<ul>
<li>If errors or warnings occur during platform startup, before listeners can be added, it is impossible
to programatically obtain information about these errors.  It is even impossible to detect if startup
errors have occurred.</li>
<li>A listener has no access to errors that have been logged before that listener was activated.
Since plug-ins cannot control when they are started, they may miss logged information that is
interesting to them.</li>
<li>Each listener that wants to maintain a representation of what has been logged must
keep their own list.  This leads to a duplication of the information available in the log file on disk.</li>
</ul>
</p>
<h2>The Solution</h2>
<p>
The proposed solution is to add an API method to org.eclipse.core.runtime.Platform that returns
the location of the log file, and to make the log file an XML file with a known DTD.  With a well known
log file name and format, third parties can use Xerces to scan or parse the log file to retrieve 
the information they are interested in.  The proposed API method is:
<pre>
/**
 * Returns the location of the platform log file.  This file may contain information
 * about errors that have previously occurred during this invocation of the Platform.
 * @return the path of the log file on disk.
 */
IPath getLogFileLocation();
</pre>
<p>
The proposed document type definition for the log file is provided below.  This format will be 
considered API.
</p>
<p>
&lt;!ELEMENT log (entry)*&gt;
<br>
<br>&lt;!ELEMENT entry (status)&gt;
<br>&lt;!ATTLIST entry
<br>&nbsp;&nbsp;&nbsp;&nbsp;date CDATA #REQUIRED&gt;
<ul>
<li><b>date -</b> the date this entry was logged, in the default java date format.</li>
</ul>
<br>&lt;!ELEMENT status (status)* (exception)?&gt;
<br>&lt;!ATTLIST status
<br>&nbsp;&nbsp;&nbsp;&nbsp;sev (ERROR | INFO | OK | WARNING) #REQUIRED
<br>&nbsp;&nbsp;&nbsp;&nbsp;id CDATA #REQUIRED
<br>&nbsp;&nbsp;&nbsp;&nbsp;code CDATA #REQUIRED
<br>&nbsp;&nbsp;&nbsp;&nbsp;msg CDATA #REQUIRED&gt;
<ul>
<li><b>sev -</b> the problem severity.</li>
<li><b>id -</b> the ID of the plug-in in which the error occurred.</li>
<li><b>code -</b> the error code, an integer value that generally has some meaning
for the plug-in that generated the error.  See <tt>org.eclipse.core.runtime.IStatus#getCode</tt>.</li>
<li><b>msg -</b> the status message, describing the error that occurred.</li>
</ul>
<br>&lt;!ELEMENT exception (exception)? &gt;
<br>&lt;!ATTLIST exception
<br>&nbsp;&nbsp;&nbsp;&nbsp;msg CDATA #REQUIRED
<br>&nbsp;&nbsp;&nbsp;&nbsp;trace CDATA #REQUIRED&gt;
<ul>
<li><b>msg -</b> the message associated with some <tt>java.lang.Throwable</tt> object.</li>
<li><b>trace -</b> a stack trace provided by <tt>java.lang.Throwable#printStackTrace</tt>.</li>
</ul>
</p>
<p>
The log file would remain at its present location, and its name would remain the same (.log).
Here is a <A HREF="sample.txt">sample log file</A> in the new XML format.
</p>
<h2>RFC Status</h2>
<p>This proposal has been accepted, implemented, and released in build 20020409.
</p>
</body>
</html>